ci(docs): deploy cloudhal.dev on push to main (#236) - #242

Owner steps (after review; nothing here has been created)

The docs-deploy environment already exists, with deployment branches main only. Until both values below exist, the workflow skips with a notice, so this PR can merge first.

1. Create the Cloudflare API token. Go to Cloudflare dashboard › My Profile › API Tokens › Create Token › Custom token.
   • Permissions: Account › Workers Scripts › Edit.
   • Account resources: include only the account that holds cloudhal-dev.
   • Zone resources: if you add the zone permission in step 4, include only cloudhal.dev.
   • Note: Cloudflare tokens can't be limited to a single Worker script; the narrowest scope is one account. Keep the token to that one account and give it no other permissions.
   • Optionally restrict client IPs, and set a TTL to match your rotation habit.
2. Store it as the environment secret. Run gh secret set CLOUDFLARE_API_TOKEN --env docs-deploy -R cloudhal-dev/cloudhal, then paste the token when prompted.
3. Store the account id as an environment variable. Run gh variable set CLOUDFLARE_ACCOUNT_ID --env docs-deploy -R cloudhal-dev/cloudhal --body <account id>.
4. Check it once by hand. Go to Actions › Docs deploy › Run workflow (on main).
   • If wrangler refuses because of the custom domain route (cloudhal.dev, custom_domain: true), add Zone › Workers Routes › Edit for the cloudhal.dev zone to the token, and run it again.
   • Then check https://cloudhal.dev/.well-known/cloudhal/keys.json.

What

RFC-0037: "a push to main deploys cloudhal-dev". .github/workflows/docs-deploy.yml:

• Triggers: a push to main that touches anything the site is built from, and workflow_dispatch. The paths are:

  • apps/docs/**: the site, its Worker and its build scripts;
  • docs/**: every page;
  • packages/core-contracts/schemas/**: /schemas/v1/*, copied by scripts/postbuild.ts;
  • packages/cli/src/cli/help.ts: the generated CLI reference, built by src/lib/reference.ts;
  • security/**: /.well-known/cloudhal/keys.json and its .sig;
  • pnpm-lock.yaml: the Astro, Starlight and wrangler versions;
  • the workflow file itself.

  yanked.json needs no deploy, because the Worker serves it live from the yank-list branch.

• One job, deploy, in the docs-deploy environment:

  • top-level permissions: {}, and contents: read on the job;
  • if: github.repository == 'cloudhal-dev/cloudhal';
  • concurrency: docs-deploy with cancel-in-progress: false, so a newer push waits instead of cutting off an upload;
  • actions pinned by SHA, the same pins as yank-list.yml; checkout with persist-credentials: false.

• Steps:

  1. Check that both CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID exist. If either is missing, emit a notice and a job summary, and run no other step.
  2. Run pnpm install --frozen-lockfile. The install runs without the token.
  3. Run pnpm --filter @cloudhal/docs run deploy, which is astro build, then postbuild, then wrangler deploy. This is the only step that gets the token.
  4. Write a job summary with the commit and the outcome.

• Test: packages/cli/test/docs-deploy-workflow.test.ts (5 tests) covers:

  • the triggers;
  • that the paths follow what the docs build actually reads (it asserts the postbuild.ts and reference.ts sources);
  • the SHA pins and read-only permissions, with no : write anywhere;
  • the concurrency group, the repository guard and the environment;
  • that the token appears once, in the deploy step only, after the install, and no inputs are interpolated into run scripts;
  • the skip.

• Docs: the key runbook's step 9, RFC-0046 §9 and RFC-0037 now say the deploy is automatic.

Checks

• actionlint is clean.
• A local pnpm --filter @cloudhal/docs run build from a plain install builds 129 pages, 25 schemas and keys.json. No other package build is needed.
• Tests, one at a time: docs-deploy-workflow 5, yank-list-workflow 6, release-workflows 14, core-contracts release-schemas 23, docs 41.
• size:check and biome are clean.

Closes #236

🤖 Generated with Claude Code